ShareWare OnLine 2/ShareWare OnLine Volume 2 (CMS Software)(1993).iso/os2/pmview85.zip/PMVIEW.DOC

Text File | 1993-04-28 | 28KB | 591 lines

INTRODUCTION
============
This is the documentation for PMView BETA VERSION 0.85. You don't have
to read this file if you don't want to, though you might miss out on
some useful information.

PMView 0.85 has many interesting new features that I'll document
quickly in the next section:

NEW FEATURES
============
1) Full PCX support and basic TARGA support.

2) New command-line flags: /INI, /IDLE_LOAD, /PAL_MAN, and /NO_PAL_MAN
join /NO_IDLE_LOAD.

3) An icon. (I *knew* we had an artist somewhere!) This icon may be
changed in future betas, so grab it if you like it! If it doesn't
appear initially, open OS/2's settings notebook for the PMView object
on your desktop, go to the "General" page, and click the _Default
button. Make sure you change the Title back after doing so!

4) A new "Settings Notebook" that replaces the huge and hideous
"Preferences dialog".

5) Real-time display of brightness/contrast/saturation or color
adjustment changes on systems that support Palette Manager. This can be
disabled from the new settings notebook, if necessary.

6) Oh yeah, a slideshow feature.

There are probably other additions that have slipped my mind for the
moment. The user interface for the slideshow is a bit limited right
now, but we *will* improve it significantly in 0.86. We decided to
release 0.85 *now* because there are several people who wanted to use
the other features (such as PCX and Targa support).

                           *      *      *

Let me introduce myself. I'm Raja Thiagarajan, Official Documenter (tm)
of PMView. Peter Nielsen, who wrote PMView, asked me to write the docs.
I'd appreciate any comments or questions about these docs, just as
Peter would appreciate any comments or questions about PMView itself.
Both of our electronic mail addresses are in Appendix 1 at the end of
this file; Peter's address can also be found by selecting _Help _About
from the PMView menu.

Which brings me to a matter I wanted to clarify: Since PMView is
currently beta software, we do NOT require you to register it. However,
if you *do* register, you *will* get a full, registered copy of the
non-beta product as soon as it's available. Further, if you have a
uudecoder and a electronic mailbox that can be reached from the
Internet, you will get *every* new beta version as it comes out.

If you have a uudecoder and an electronic mailbox that can be reached
from the Internet, you can join our beta program by sending me an
e-mail message. It doesn't cost anything; we just expect you to fill
out an e-mailed survey form and give us bug reports (or other
feedback!) on new versions of PMView as they're released. To join our
beta program, just drop me a line at [e-mail].

All the above provisions are void where prohibited, and subject to
change (though that's not likely).

Please read the License and Warranty information in LICENSE.DOC. If
you've read some of the repressive provisions of other companies'
software, you may be in for a pleasant surprise.

(I'll just make one short comment here: Since *this* version of PMView
is shareware, you are permitted [even encouraged!] to pass on the
PMView ZIP file. You may NOT modify this file, or pass on any of its
individual components.)

PROGRAM REQUIREMENTS
====================
To use this program, you *must* be running OS/2 2.0 (or later). PMView
is a fully 32-bit program. (This is part of the reason PMView is so
fast. The other part is because Peter has spent literally *hundreds* of
hours fine-tuning the decoding routines by hand, in 80486 assembly
language.)

Our beta testers report that you *must* be running with CSD 6055 (also
known as "the Service Pack"), or preinstalled OS/2 2.00.1, or one of
the OS/2 2.1 betas. The version of OS/2 2.0 that IBM sold initially had
some bugs in the Palette Manager subsystem that will prevent PMView
from running. (Also, some users have reported trouble with the March
6.498 beta, so be careful with that beta.)

USING THE PROGRAM
=================
To use the program, set the PMVIEW_INI environment variable (see the
next section), place PMVIEW.EXE somewhere on your path and enter the
command

    PMVIEW [flag(s)] [filename]

where "flag(s)" and "filename" are optional. The flags are documented
two sections below this one. "Filename" is an optional name of a file
you want to view. (If you don't  provide a filename, PMView will start
up with a black screen.) The filename can include a drive, directory
path, or both. If you don't give an extension, PMView will try to
"guess" it anyway. (Specifically, if you leave off the extension and
PMView can't find a file with that name, it'll try the extensions .BMP,
.GIF, .JPG, .TGA, and .PCX, in that order. You can modify this using
the _Extensions page on PMView's settings notebook.)

ENVIRONMENT VARIABLES
=====================
To backtrack a little, there is an OS/2 environment variable that
PMView uses: PMVIEW_INI. This variable specifies the filename
(including full path) that PMView should use for storing its options.
If this environment variable is not set, PMView will create the file
PMVIEW.INI in the current directory and store its information there.
Thus, if you don't want *lots* of copies of PMVIEW.INI scattered around
your hard drive, we recommend that you put the line

   set PMVIEW_INI=C:\OS2\PMVIEW.INI

in your CONFIG.SYS. (Of course, you can use any other path or filename
that you want; we find it convenient to keep all our OS/2 INI files in
one place.)

FLAGS
=====
There are five optional flags that you can use when invoking PMView.

/IDLE_LOAD, /NO_IDLE_LOAD: Use these flags to temporarily force (or
disable) idle-time priority for PMView's image-loading thread. See
BUGS.DOC for a discussion of idle-time priority.

/PAL_MAN, /NO_PAL_MAN: Use these flags to temporarily force (or
disable) the use of Palette Manager.

/INI: Use this flag to temporarily set the pathname for PMView's INI
file. For example:

    PMVIEW /INI=D:\TEMP\PMVIEW.INI

will cause this PMView session to read (and write) its settings to
D:\TEMP\PMVIEW.INI instead of the file specified by the PMVIEW_INI
environment variable. For instance, you could have several different
INI files with different settings and put an icon for each on your
desktop, with different "/INI=" flags in the Parameters field of each
object's settings notebook.

PMVIEW COMMANDS
===============
Here's a list of the menu commands and a comment on what each one does:

_File _Open: This starts a dialog box that lets you open (i.e., load
and look at) a new file. This should be fairly straightforward.
Initially, PMView will list all the *.BMP, *.GIF, *.JPG, *.TGA, and
*.PCX files in the current directory. To change this, type the filename
filter you want in the "Open Filename:" area and then click the "Open"
button. For instance, to get a list of GIF files that start with "ray",
enter RAY*.GIF and click "Open". You can put several of these together,
separated by semicolons (";"). So, for instance, "RAY*.GIF;*.BMP" will
list all the files that either start with "RAY" and have the extension
"GIF" *or* have the extension "BMP."

A shortcut for selecting one of these extensions is to pick it off the
"Type of file:" list. Check it out.

You can use the ^O (that is, Control-O) shortcut key to invoke this
command at any time, as long as a slideshow isn't running. ^O will work
even if PMView is in Full Screen mode (e.g., after hitting F3) or
iconified. If you have the "Override system colors in fullscreen mode"
option set, this dialog will appear, but it will *not* necessarily be
readable. That's *why* overriding system colors isn't the default.

To start up a slideshow, simply select several files before clicking
the "Open" button. The images will be loaded, one at a time, in
alphabetical order. (I *know* that's dumb, but we can't fix it until we
do 0.86.) You can jump forward to the next image by pressing either
mouse button, or by hitting the SPACEBAR. To end the slideshow, press ESC.

_File _Reopen: This reloads your current file from disk, which means
any changes you had made to it (or your view of it) are lost.

_File _Save: This feature doesn't work in the unregistered version.

_File Save _as: Neither does this.

_File _Delete: This deletes the file that you're viewing. See BUGS.DOC
for a note about a "feature" of WPS that affects this. You can use ^D
as a shortcut.

_File E_xit: This quits PMView and returns you to OS/2. ^X is the
shortcut key.

_Edit: All these commands change the image that you have loaded in
PMView. (The original image file is unaffected, of course.)

_Edit _Flip: This turns the image upside down. If you had an image of a
big "M", it would look like the image of a big "W".

_Edit _Mirror: This reverses left and right on the image. If you had an
image of a left parenthesis, it would look like a right parenthesis.

_Edit Rotate _CW: This rotates the image clockwise by 90 degrees. An
arrow that pointed up would now point right.

_Edit Rotate CC_W: This rotates the image counterclockwise by 90
degrees. An arrow that pointed up would now point left.

_Edit _Brightness/Contrast: This opens a control that lets you adjust
the brightness, contrast, and saturation of your image. Brightness and
contrast work pretty much the way they do on a TV set. Saturation
refers to how much color appears in the image (some TV sets have a
control marked "color" that does this). If you turn the saturation all
the way down, you'll get a black-and-white image.

Peter notes that if you're handling 24-bit images and don't use the
Palette Manager, you should adjust saturation *last*. This is because
the other adjustments take *twice* as long when saturation has been
moved away from 0% under those circumstances. To reiterate: If you're
running OS/2 in 24-bit (or 15- or 16-bit) mode, or if you've loaded a
24-bit image (i.e., a Targa, JPEG, or 24-bit BMP image) and disabled
Palette Manager, change saturation *last*.

If you change your mind later, you can come back to this control and
press the Reset button. This will return you to your original settings
for brightness, contrast, and saturation.

_Edit Color _Adjustment: This opens a control that lets you adjust the
relative strengths of red, green, and blue in your image. As with
_Brightness/Contrast, you can use Reset if you change your mind later.

_Edit _Negative: This creates a "negative" of your image; for example,
black pixels will become white. Of course, if you do this twice, you'll
have your original image again.

_View: These commands change how you see the image, but don't actually
change it. They all have shortcut keys.

_View _Full Screen: Choosing this command (or pressing F3) erases your
WHOLE screen (and not just the PMView window) and draws the image on
it. F3 acts like a toggle; pressing it again redraws the screen and
puts the image "back" in the PMView window.

(Why would you want to do this? If you have an image that's as large as
the whole screen, you won't be able to see it while you have PMView's
window border, menu bar, title bar, etc. on the screen. For instance,
if you installed the optional bitmaps with OS/2, try loading
OS2LOGO.BMP. You won't be able to see the whole image because it's too
big. Now press F3. The whole image will be visible. Press F3 again to
go back to having the image in the PMView window.)

PMView's settings notebook has a _Fullscreen page that has three
settings to handle centering or scaling the image when you press F3.
See below under _View S_ettings for more information.

_View _Size to Image: Choosing this command (or pressing F4) will cause
the image to be drawn at "actual size" and then shrink or grow the
window so that you can see the whole image and nothing but. Unless:
   1) The image is too big (in which case you should try F3 instead), OR
   2) The image isn't wide enough (PM will NOT let the window become
     too narrow for the menu bar), OR

   3) You have "Never" selected as your option in "Automatically Adjust
      Window Position" (on the _Window page of PMView's settings notebook)
      and the only way to show the whole image would be to move the
      window. (This might happen if your window is positioned too close to
      the right or bottom edge of the screen.) In this case, you can change
      the option to "When required"; see the _View S_ettings documentation
      below.

_View _Refresh: Choosing this (or pressing F5) will redraw the image in
the window. You may want to do this if (for whatever reason) the image
gets corrupted. Unfortunately, as of this writing, there is a bug in
*all* the available 256-color screen drivers that support Palette
Manager. (This is not a bug in PMView.) When you drop down a menu and
then get rid of it, the area that was under the menu is drawn with the
wrong colors. To redraw the image with the correct colors, hit F5.

_View S_ettings: Ding, dong, the witch is dead! The huge, hideous,
crowded _Preferences dialog has been replaced by a notebook that lets
you control PMView's many options. Taking one page at a time:

   _View:

-- Center image if it is smaller than window: If set, PMView will draw
an image that's smaller than its window in the center of the window. If
not set, PMView will draw the image in the upper left corner.

-- Scale image to fit window size. If set, PMView will stretch an image
that's smaller than the window so that it fits perfectly either
horizontally or vertically. Otherwise, the image will always be drawn
at "actual size". All shrinking and stretching in PMView is
proportional; circles will *always* stay circles.

   _Fullscreen:

-- _Center image if it is smaller than screen: If set, PMView will center
the image when drawing in Full Screen Mode. Othewise, the image will be
drawn in the upper left corner of the screen.

-- Scale image if it is _larger than screen: If set, PMView will shrink
images so they will fit onscreen, if necessary. As mentioned above,
shrinking is done proportionally.

-- Scale image if it is _smaller than screen: If set, PMView will
stretch images so that they either reach completely across the screen
vertically or horizontally. Again, stretching is proportional.

As is noted on the page, two other options that modify Full Screen mode
can be found elsewhere.

   _Window:

Automatically adjust window size and position:

-- When _loading a new image: If set, PMView will automatically adjust
the window's size and position to display newly-loaded images at actual
size.

-- If image size changes when _editing: If set, PMView will adjust the
window's size and position if it's appropriate during an edit. For
instance, if you take a tall, narrow image and rotate it, it will
become a short, wide image. If this option is set, PMView's window will
resize (and possibly move) accordingly. Otherwise, you might get a
horizontal scroll bar and some blank space in your window.

Automatically adjust window position:

o _Never
o When _required
o _Always move to upper left corner

If you pick the first option, the upper left corner of PMView's window
will never budge. If you pick the second option, PMView will leave the
upper left corner in place *unless* moving it a short distance will let
you see your whole image. Then it will move. Finally, "Always move to
upper left corner" means that your window will move to the upper left
corner of your screen every time you hit F4 (or load a new image, if
the first option on this page is checked).

_Loading:

Loading/Startup options:
o Startup _minimized (iconized)
o Normal
o Fullscreen each loaded image automatically

If you pick the first option, PMView will start up minimized when you
*first* load it. The second option will make it start up with the size
of the image you specify on the command line (or the size it was when
it last closed). (To make it do this *every* time it loads an image,
select "When loading a new image" on the window page.) The last
option will make PMView go into Full Screen mode *every* time it loads
an image.

(Why would you want to start up PMView iconified? Suppose you have
associations set in OS/2 so that whenever you double-click on the name
of a GIF file, it starts up PMView automatically. It's quite convenient
to be able to double-click on *several* GIF files and have each one
appear as an icon at the bottom of your screen, so you can pick which
ones to look at *after* they're done loading. One of our beta testers
wanted this feature, so here it is. He also said he'd register if we
added this feature, so I'm waiting for his check to arrive ;-)

Progress indicator options:
o _Never show progress indicator
o _Hide when PMView is started with a filename
o _Always show progress indicator

These options decide the visibility of the progress indicator, that
sliding bar that some people love and some people hate. Select the
first option if you hate seeing it, select the last if you like seeing
it. If you select the second option, PMView will display the progress
indicator *except* when you first start up with a filename on the
command line.

_Slideshow:

Here's where you set the options for a slideshow. To run a slideshow,
select several files while doing _File _Open. Then use SPACEBAR (or
either mouse button) to move forward an image or ESC to end the
slideshow.

o Manual
o Automatic
If you select manual, you must always move to the next image manually.
If  you select automatic, you also have the option of waiting for the
next slide to be loaded automatically.

Delay between images
Here, you specify how many seconds PMView spends before automatically
moving to the next image. In order to work around a bug, we set the
minimum delay to 5 seconds. This "lower limit" will almost certainly be
removed in 0.86.

-- _Cycle slideshow: If this option is set, the slideshow will go back
and load the first image after it finishes with the last one.
Otherwise, you'll get a message box at the end of the slideshow.

_Directory:

On this page you can type the paths for the default load directory
(where PMView will initially go the first time you do a _File _Open)
and the default save directory (where PMView will save files by
default). File saves are *not* enabled in the unregistered version of
PMView.

_Extensions:

This page is allows you to change the ordering, lettering, or comments
on the extensions that PMView loads. For instance, if you're running
HPFS and use the extension .JPEG for your JPEG files, you can type
"JPEG" in the Extension field, type "My JPEGs" in the description
field, and click "Ok >>". Then whenever you do a _File _Open, PMView
will *also* display files with the extension of *.JPEG. What's more "My
JPEGs" will appear in the Type of File list. *And* if you enter PMVIEW
filename at an OS/2 prompt, PMView will be able to add the .JPEG
extension automatically. Way to go, Peter!

_Palette:

-- Use _palette manager: If on, PMView will use the palette manager to
display images. (Of course, if you don't have palette manager support,
this option won't be available.) Why would you *disable* palette
manager support? Two reasons: one, your screen driver might have buggy
palette manager support, or two, you might want to "preview" what your
image might look like if you used it as a desktop background ....

-- _Smooth palette change in adjustment dialogs: If on, PMView will use
palette animation to show brightness/contrast/saturation or color
adjustment changes *in real time*. Pretty nifty!

-- _Override system colors in Full Screen mode: If on, PMView will use
all 256 colors in Full Screen mode, rather than letting OS/2 reserve 20
for the user interface. Of course, if you chose this option and then
type ^O, you may not be able to read the resulting dialog box....

Spe_cial:

-- Use PMView's _own scaling routines: If on, PMView will use its own
scaling routines rather than using the ones built into the screen
driver. (As of this writing, I know of four platforms that support
palette manager, and *three* of them don't scale correctly.) Even if
you have a platform that scales correctly, you may want to try this
option because it may be *faster* this way. Of course, it will take up
more memory.

-- Use _idle time loading and saving: If on, PMView will use the lowest
priority in OS/2 when it loads and saves files. This can be a problem
if you're running a "greedy" OS/2 or DOS program that "eats" lots of
CPU; idle-time threads *never* have their priority boosted and can thus
get "stuck". On the other hand, if you turn this option on, PMView will
use ordinary priority, which may degrade your multitasking performance
while it's running.

Whew! We're done with the settings notebook! If you think it took a
long time to read all that, just imagine how long it took me to *write*
it ;-). On to the last menu, which is _Help.

_Help _System: This gives information on your system's current status:
what version of OS/2 PM you're running, how wide and tall your screen
is (in pixels), whether your screen driver supports Palette Manager,
how many colors you have, how many physical colors you have (what's the
difference? Beats me) and how much physical RAM you have.

_Help _About: Finally, this displays product information about PMView,
as well as information about how to register the program. If you like
PMView, please support shareware by registering it. Registered versions
of PMView will include working _File _Save (and _File Save _As)
commands, a niftier icon, and probably some other extras as well.

If you've made it this far, congratulations. Here's a cute trick for
you to try: Make OS/2 minimize to the desktop (by opening OS/2
System->System Setup->System and selecting "Minimize _window to
desktop" on the _Window page of the notebook). Now, load a colorful
image and then minimize PMView. Pretty neat, huh? Thanks to Steve Ryner
(the Official Artist [tm] of PMView) for discovering this trick.

ACKNOWLEDGEMENTS
================
The Graphics Interchange Format (c) is the Copyright property of
CompuServe Incorporated. GIF (sm) is a Service Mark property of
CompuServe Incorporated.

This software is based in part on the work of the Independent JPEG Group.

APPENDIX 1: HOW TO CONTACT US
==============================
Both Peter and I would love to hear from you. If you have any comments,
suggestions, or wishes for new PMView features, please write to us.

Peter can be reached on the Internet at [e-mail] or
[e-mail]. He doesn't have a CompuServe account, but you can
send CompuServe mail to me and I will pass it on. (See below for my
CompuServe address and a caveat on its use.)

Alternatively, you can send Peter a paper letter at Gertrudsgatan 22 D
73, SF-20520, Turku, Finland. (Take into account the delays of
international mail when you do this!)

You can reach me, Raja Thiagarajan, on the Internet at
[e-mail]. Alternatively, you can write me on
CompuServe at 72175,12. Generally speaking, I read my Internet mail
almost every day (except for holidays!), but only read my CompuServe
mail about once a week.

If you prefer to support the U.S. Post Office, you can send me paper
mail at 4423 East Trailridge Road, Bloomington, IN 47408-9633. However,
I recommend that you save a tree (and some time) by sending me e-mail
instead.

APPENDIX 2: WHERE TO GET NEW VERSIONS OF PMVIEW
===============================================
When a new version of PMView comes out, the first thing we will do is
send it to registered users. If you give us an e-mail address when you
register, we will e-mail the new PMView to you immediately.

After we have finished sending copies to registered users, we will post
a copy to Hobbes on the Internet. This is the world's best ftp site for
finding OS/2 software. Its official designation is ftp-os2.nmsu.edu.
PMView will be put in the /pub/uploads directory initially; after a
while, it will be moved to the /pub/os2/2.x/graphics directory.

After we have posted a copy to Hobbes, we will post a copy to
CompuServe. [*********WHERE!?!?!?!?!?*********] So, to find the latest
version of PMView, look on Hobbes and CompuServe.

NOTE: The above appendix refers to new release versions of PMView. New
beta versions are sent to people on our beta list (with registered
users getting them first, if it's necessary to do it in more than one
batch ;-) and may not end up on Hobbes. If you *really* want to get all
the new beta versions of PMView, send us a bug report (or a short note
saying you want to join the beta program) and an e-mail address at
which you can accept big, uuencoded mail messages from the Internet. We
reserve the right to limit the number of beta testers.

APPENDIX 3: TECHNICAL SPECIFICATIONS
====================================
Architecture: 32 bit, 4 threads
Internal image format: 8 and 24 bit
Transformations: All formats
Palette Manager support: Yes, 256 colors (if your display driver
                             supports Palette Manager)
True Color support: Yes, 24 bit, 16.7 million colors or less (if your
                             display driver supports True Color)

Image formats that can be read and written
------------------------------------------
GIF: Full support: 87a, Basic support: 89a

BMP (OS/2 1.x): Full support: 1, 4, 8 and 24-bit bitmaps or bitmaparrays.
BMP (OS/2 2.x): Full support: 1, 4, 8 and 24-bit bitmaps or bitmaparrays.
                              HUFFMAN1D, RLE_4, RLE_8 and RLE_24 compressions
                              supported.
BMP (Windows 3.0): Full support: 1, 4, 8 and 24-bit bitmaps.
                   RLE_4 and RLE_8 compressions.

JFIF: Support in accordance with the Independent JPEG Group's revision 4.0.

PCX: Full support

TARGA: PMView supports Targa formats 1, 2, 3, 9, 10, and 11.
#1 is uncompressed, color-mapped images with 16, 24, or 32-bit palette entries
#2 is uncompressed RGB images with 15, 16, and 24 bit support
#3 is uncompressed grayscale (256 shades) support
#9 is RLE color-mapped images with 16, 24, or 32-bit palette entries
#10 is RLE RGB with 15, 16, and 24 bit support
#11 is compressed grayscale (256 shades) support
These are the most popular Targa formats. We've succeeded in loading
every Targa file that we've found. If PMView fails to load a Targa file
that you need, please contact us so we can figure out how to support
your file's format in our next release.

APPENDIX 4: DEVELOPMENT SYSTEM
==============================
If you're curious, Peter Nielsen is developing PMView on the following
system:

        IBM PS/2 model 95       486/50MHz
                                64 Mb RAM
                                2400 Mb hardfile
                                XGA-2 + 21" multisync
        IBM OS/2 2.0 GA + SP

He's using the following tools:
        IBM C-SET/2
        IBM OS/2 developers toolkit + IBM Workframe/2
        Microsoft MASM 6.0
        Solution System's BRIEF 3.0 for OS/2

Th-th-that's all, folks!

Raja Thiagarajan / PMVIEW.DOC / 4-28-93 release